home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 7 / BBS in a Box - Macintosh - Volume VII (BBS in a Box) (January 1993).iso / Files / Prog / D-G / Demo of Resorcerer 1.1.1.cpt / Resorcerer 1.1 Read Me Files / Balloon Help Help 1.1 < prev    next >
Text File  |  1992-05-07  |  12KB  |  96 lines
  1.  
  2. Notes On Creating Balloon Help Using Resorcerer 1.1
  3. ===============================================
  4.  
  5. Menus
  6. -----
  7.  
  8. To add balloon help to a ‘MENU’ (popup, heirarchical, or standard), you need to create an ‘hmnu‘ resource whose resource ID is the same as the menuID field within the ‘MENU’ resource.  The menuID field is nearly always the same as the ‘MENU’ resource ID, and it is a good idea for all ID’s to be the same.
  9.  
  10. Before creating the ‘hmnu’ resource, open the ‘MENU’ resource and turn on command numbers so that you can refer to the menu command indices while you are editing the help resource.
  11.  
  12. The ‘hmnu’ resource consists of a variety of header data fields followed by a list of balloon help message records.  In general you can ignore all of the header fields in favor of their default values.
  13.  
  14. Following the header data, there is a “Missing message” record, whose type is usually “Skip missing message”.  If you are going to add explicit help messages for the menu items elsewhere, you don’t need a missing message record and you can leave it alone.  Otherwise, you may want to enter a default message that the Help Manager will display for menu items that don’t have their own explicit balloon messages.
  15.  
  16. Initially, the list of message records that follows will be empty.  To add a new item (message record) to the list, place the blinking list insertion caret just after the horizontal divider line that labels the item below it, and click on the New button.  To add more than one message record, click on the New button that many times.
  17.  
  18. The first message record (labeled #1) in the ‘hmnu’s list is reserved for any help to associate with the *title* of the menu, not with menu command #1.  If there is no title, you should set the message record type to “Skip missing item”.
  19.  
  20. Subsequent balloon message records in the list are scanned sequentially in conjunction with the menu commands.  Typically, there will be one message record for each item in your menu.  Divider lines count, so you have to create empty skip item message records as placeholders.  For instance, a menu that looks like
  21.  
  22.         File
  23.                 New
  24.                 Open…
  25.                 ----
  26.                 Save
  27.                 ----
  28.                 Quit
  29.  
  30. might have an ‘hmnu’ something like this:
  31.  
  32. Header info
  33. Missing message record (set to “Skip missing item”)
  34. List:
  35.         #1:    Message record for “File” title
  36.         #2:    Message record for “New” command
  37.         #3:    Message record for “Open…” command
  38.         #4:    Message record for divider (set to “Skip missing item”)
  39.         #5:    Message record for “Save” command
  40.         #6:    Message record for divider (set to “Skip missing item”)
  41.         #7:    Message record for “Quit”
  42.  
  43. Each message record lets you set the four types of messages (enabled, disabled, checked, or other) either directly within the message record, or as a reference to another resource.  The easiest thing to do is enter your messages directly as text strings into the record.  To do this, set the message record type (using the little popup) to “Use these strings”, then open (double-click on) each of the four fields and enter the text.
  44.  
  45. If the message record keeps its help in a separate resource, usually a string list (‘STR#’), you can open the referenced resource by Option-double-clicking on the resource ID field in the message record to edit it there.  The content of the balloon can also be taken from a 'PICT' resource, a styled 'TEXT' resource, or a 'STR ' resource.
  46.  
  47. To try out the messages you have entered so far, close the ‘hmnu’ resource, switch over to the ‘MENU’ editor, turn Balloon Help on in the Help menu, and try the sample menu out in the menu bar.  The Editor installs the 'hmnu' and copies of all the resources it in turn references (strings, pictures, styled text, named resources) in such a way that they will be visible to the Help Manager.  It does this as soon as your mouse moves within the menu bar, so that you can see the balloons for the menu title without clicking on anything.  When you pull your sample menu down, you can try out the help balloons you have built so far.
  48.  
  49. During balloon try out, only balloon help in the top-most sample menu is shown; help for hierarchical sub-menus won't show up, even though the sub-menus and their colors are resolved.  You can open the hierarchical sub-menu, though, and try its balloon help out while editing it as a top-level menu.
  50.  
  51. Finally, be very cautious about using CompareItem message records.  If you have a menu in which a command changes state, it is more robust to use a Named Resource item than to place two CompareItem message records one after the other.
  52.  
  53.  
  54. Dialogs
  55. ------
  56.  
  57. To add balloon help to the items (‘DITL’) in a dialog, you must add a special invisible “helpItem” to the item list.  This helpItem will link the item list to a help resource containing the balloon messages to use.  You can do this by opening the dialog and choosing Balloon Help… from the Item menu.  If there are no help items (there can be any number, but one is the usual number), click on the New button to create one.  Typically, you will want the referenced help resource to have the same resource ID as the dialog and its item list, which is what it will default to.  You can tell when a dialog has at least one helpItem in its item list: the Balloon Help... command in the item menu will be checked.
  58.  
  59. Each helpItem contains a reference to either an ‘hdlg’ or an ‘hrct’ resource.  ‘hdlg’ resources declare help messages to be displayed when the mouse passes over the bounds of items in a dialog; ‘hrct’ resources declare messages to be displayed when the mouse passes over arbitrary rectangular areas within the (dialog) window.
  60.  
  61. Click OK to create the helpItem.  If you are running Resorcerer 1.1, click on the Edit & OK button (or double-click on the selected helpItem in the list) to automatically open or create the referenced ‘hdlg’ or ‘hrct’ resource.  This also turns Show Item Numbers on if you haven’t already done so.
  62.  
  63. As with ‘hmnu’ resources, ‘hdlg’ resources begin with a header whose entries you can generally ignore in favor of their default values, followed by a missing message record, followed by a list of message records.  There is one extra field in the header, an item number offset, that lets you assign the item to which the start of the message record list will belong.  If the offset value is 0 (the default), then the first message in the list will be matched to item #1; if the offset value is 4 (for example), then the first message of the list would be matched to #item 5.  What this allows you to do is create a small ‘hdlg’ resource with, say, only 3 message records in its list, and assign those 3 messages to any sequence of 3 items in a large dialog item list, such as items #39, #40, and #41, without having to insert an initial sequence of 38 “Skip missing message” records.
  64.  
  65. Following the header is the missing message record, which will contain or refer to the text to be displayed when the Help Manager cannot find anything better to show for the item the mouse is pointed at.  You can usually leave this set to its default also, “Skip missing message”.
  66.  
  67. Following the missing message record is a list of message records, which corresponds to a sequence of items in your dialog’s item list.  Normally, message record #1 corresponds to dialog item #1, and the easiest way to enter help text is to set the record type popup to “Use these strings” and then enter the text for each item directly into the record.  For items that don't need help messages, primarily staticText items, or disabled graphic user items, just set the message record type to “Skip missing message”.  For others, enter the text as appropriate for the possible item states, enabled, disabled, checked, or other.  The checked and other messages can be left blank, except in the case of certain types of Control items (see Inside Mac, VI, 11-36).  You can go back to your dialog window and refer to the now-showing item numbers to keep yourself in sync. (Future versions of Resorcerer will do this automatically!).
  68.  
  69. Each message record in an ‘hdlg’ begins with a Tip Position and Hot Rect alternate rectangle offset field, which can usually be left set to their zero defaults.  The Tip Position is always an offset with respect to the upper left corner of the item bounds.  If it is (0,0), the Help Manager places the tip inset 10 pixels from the lower right corner of the item, space willing (otherwise, it tries other corners).  The alternate Hot Rect field is not a rectangle in and of itself; rather, each coordinate is the offset to add to the dialog item bounds to create the actual Hot Rect alternate rectangle.  Thus, when the value is (t,l,b,r)=(0,0,0,0), the Hot Rect is the same as the item bounds.  If the Hot Rect is smaller than the item, there will be more room on the screen for the Balloon; if the Hot Rect is greater in size than the item bounds, the Balloon will be more likely to be positioned complete outside the actual item bounds, ensuring that you can see the item.
  70.  
  71. For areas in the dialog window that don’t represent items in the ‘DITL’, but for which you want balloons to show, you need to use an ‘hrct’ resource, rather than an ‘hdlg’.  These are basically the same, except that the coordinates of the Hot Rect fields in the message records are actual rectangles, not offsets from item bounds.
  72.  
  73. You can screen copy the value of these rectangle fields in Resorcerer 1.1.  Open the rectangle field for editing and click on the Set button; or just Option-double-click on the rectangle field.  When you drag the marching ants marquee over another window, such as your dialog window, you constantly record (in local coordinates) its position back in the 'hrct' resource.  When the upper left corner of the marquee is positioned in your dialog window, you can click and drag the lower right corner to its required size.
  74.  
  75. This is not an ideal interface, of course; we hope to have ‘hrct’/‘hdlg’ editing completely integrated into the Dialog Editor itself in the next version of Resorcerer.  But this will suffice for the time being.
  76.  
  77.  
  78. Windows
  79. --------
  80.  
  81. To attach balloon help to a window that is not a dialog, you must use an entry in an ‘hwin’ resource.  Each entry in this resource corresponds to a different type of window, and links an ‘hrct’ resource to the window.
  82.  
  83. The window to link the help to is specified in one of two ways.  In the first method, the Help Manager searches the window list for a window whose title begins with the same characters as you place in the ‘hwin’ entry.  You don’t need to specify the whole title; any initial prefix will do if you set the number of characters to check for.
  84.  
  85. This method does not work well for windows whose titles change, such as document windows.  In this case, you can link a help resource to a window via its windowKind value.  To do this, place *the negative* of a window’s windowKind value in the title string length field in the ‘hwin’ resource.  The Help Manager will search the window list for windows having the given windowKind value, and then associate the balloons in the referenced 'hrct' resource with areas of the matching window if it finds one.
  86.  
  87. This latter method requires that you know something about the inner workings of the application whose window’s you are adding help to.
  88.  
  89.  
  90. Finder Icons
  91. -----------
  92.  
  93. To create some Balloon Help that the Finder will show when you point the mouse at your application’s icon, create an ‘hfdr’ resource with resource ID -5696.  Create a single message record in the list, and enter the text of the message you want to show up in a balloon when the user points at your application icon.  Or do something fancy with styled text or a picture.
  94.  
  95.  
  96.